~ chicken-core (master) /manual/Egg specification format
Trap1[[tags: manual]]2[[toc:]]345== Format of the egg description file67An egg description is basically an association list holding8information about the components of the egg. An egg may contain9multiple components: libraries, programs, Scheme or C include files10and arbitrary data files. Dependencies between eggs can be11specified as can be dependencies between components of an egg.1213A list of valid properties follows.1415=== Global properties1617==== version1819 [egg property] (version STRING)2021Specifies version string for this egg. {{STRING}} should have22the format {{<MAJOR>.<MINOR>.<PATCHLEVEL>}}, where only the23{{<MAJOR>}} part is mandatory.2425Eggs from remote egg servers are automatically versioned - the26version is part of the protocol to retrieve the egg and does not27have to be specified in the {{.egg}} file. Eggs installed from28local directories (see below) should explicitly specify a version.2930==== synopsis3132 [egg property] (synopsis STRING)3334Gives a short description of this egg.3536==== author3738 [egg property] (author STRING)3940Names the author or authors of the contained code.4142==== maintainer4344 [egg property] (maintainer STRING)4546Names the maintainer of this code, if different from author(s).4748==== category4950 [egg property] (category NAME)5152Gives the category under which this egg should be contained.53See [[https://wiki.call-cc.org/chicken-projects/egg-index-5.html|the egg index]]54for a list of currently used categories.5556==== license5758 [egg property] (license STRING)5960Names the license under which this code is available.6162==== dependencies6364 [egg property] (dependencies EGG ...)6566Lists eggs that this egg depends on, and which should be67built and installed if they do not already exist in the repository.68{{EGG}} should be whether a symbol or a list of the form69{{EGGNAME VERSION}}, where the former means to install the70newest available egg with this name and the latter specifies71a specific version or higher. {{EGGNAME}} may also be the string or72symbol {{chicken}}, in case you want your extension to depend73on a minimum required CHICKEN of {{VERSION}} or newer.7475This property can also be used to specify a minimum version of CHICKEN76required by the egg. For example, to require at least CHICKEN 5.3.0:7778<enscript highlight=scheme>79(dependencies (chicken "5.3.0"))80</enscript>8182==== test-dependencies8384 [egg property] (test-dependencies EGG ...)8586Lists eggs that are required for this egg to run the tests87(if tests exist.) This only has an effect if the {{-test}}88option has been given to {{chicken-install}}.8990==== build-dependencies9192 [egg property] (build-dependencies EGG ...)9394Lists eggs that are build-time dependencies for this egg,95i.e. there are required to build, but not to run the contained96code. Currently this is treated identical to {{dependencies}}.9798==== foreign-dependencies99100 [egg property] (foreign-dependencies NAME ...)101102Lists external dependencies like native code libraries103or system-specific packages and is currently only used for104documentation purposes.105106==== platform107108 [egg property] (platform PLATFORM)109110Specifies for which platform this egg is intended. {{PLATFORM}}111should be a symbol naming the target platform ({{windows}}, {{linux}}112or {{unix}}) or a boolean combination of platform values, allowed113are {{(not PLATFORM)}}, {{(or PLATFORM ...)}} and {{(and PLATFORM ...)}}.114If the expression can not be satisfied, then installation of this115egg will abort.116117==== distribution-files118119 [egg property] (distribution-files FILE ...)120121List of files required for the installation of the egg. This122form is not handled by chicken-install, but by henrietta-cache to123determine what to cache. If the repository contains additional124files that are unneeded for the egg to be installed, you can list125all the required files in this clause to reduce the amount of data126cached by egg servers.127128==== components129130 [egg property] (components COMPONENT ...)131132Lists components (extensions, programs, include- or data files) that133this extension installs. See [[#component-types|Component types]] and134[[#component-properties|component properties]] for information on how135to specify component-specific information.136137==== host138139 [egg property] (host PROP ...)140141Recursively process {{PROP ...}}, but only for the host (build)142platform, in case this is a "cross-chicken", a CHICKEN installation143intended for cross compilation.144145==== target146147 [egg property] (target PROP ...)148149Recursively process {{PROP ...}}, but only for the target150platform, in case this is a "cross-chicken", a CHICKEN installation151intended for cross compilation.152153==== component-options154155 [egg property] (component-options OPTIONSPEC ...)156157Specifies global options for all programs and extensions compiled for this egg.158{{OPTIONSPEC}} may be {{csc-options}}, {{link-options}} or {{linkage}} specifications.159160==== cond-expand161162 [egg property] (cond-expand CLAUSE ...)163164Conditionally expand egg specification forms, depending on system165features. Each {{CLAUSE}} should be of the form166{{(TEST PROPERTY)}} where {{TEST}} is a feature identifier or a167conditional form, in the same syntax as used in the {{cond-expand}}168syntactic form.169170In addition to normal system-wide feature identifiers, feature identifiers171given via the {{-feature}} option to {{chicken-install}} are visible in172the tests. Also, the features {{target}}, {{host}}, {{dynamic}} and173{{static}} are visible, depending on surrounding egg specification174forms for constraining mode and linkage.175176==== error177178 [egg property] (error STRING ARG ...)179180Signal an error and abort processing. Mostly useful inside {{cond-expand}} forms.181182=== Component types183184==== extension185186 [egg property] (extension NAME PROP ...)187188Specifies an extension library component. The properties189{{PROP...}} are processed recursively and apply only to this190component.191192==== data193194 [egg property] (data NAME PROP ...)195196Specifies one or more arbitrary data files.197198==== generated-source-file199200 [egg property] (generated-source-file NAME PROP ...)201202Specifies a file that is generated during the process of building203the egg.204205==== c-include206207 [egg property] (c-include NAME PROP ...)208209Specifies one or more C include files.210211==== scheme-include212213 [egg property] (scheme-include NAME PROP ...)214215Specifies one or more Scheme include files.216217==== program218219 [egg property] (program NAME PROP ...)220221Specifies an executable program.222223==== c-object224225 [egg property] (c-object NAME PROP ...)226227Specifies a compiled C/C++ object file. Usually this component type228is required if you want to link a separately compiled C/C++ module229with your extension or program. C-objects are compiled like Scheme230source files with the {{csc}} tool to ensure the same C compiler231options and toolchain is used as for regular Scheme files compiled232to C. If you want to pass compiler-specific options to the build233of the C object, use the {{csc-options}} property and precede234C compiler options with {{-C}}.235236Components of this type are never installed, they just exist at build time.237238==== installed-c-object239240 [egg property] (installed-c-object NAME PROP ...)241242Similar to {{c-object}}, but the compiled object file will be installed in the243extension repository.244245=== Component properties246247==== host248249 [egg property] (host PROP ...)250251Process {{PROP ...}} recursively for the current component, but252apply the properties only to the host (build) part, when using253a CHICKEN installation intended for cross-compilation.254255==== target256257 [egg property] (target PROP ...)258259Process {{PROP ...}} recursively for the current component, but260apply the properties only to the target part, when using261a CHICKEN installation intended for cross-compilation.262263==== linkage264265 [egg property] (linkage LINKAGE)266267Define whether the component should be linked dynamically or268statically. {{LINKAGE}} can be {{static}} or {{dynamic}}. This269property only makes sense for extension libraries.270271==== types-file272273 [egg property] (types-file [NAME])274275Specifies that a "type-database" file should be generated and276installed for this component. This property is only used for277extension libraries. The name is optional and defaults to the278name of the extensions (with the proper extension).279280If {{NAME}} is a list of the form {{(predefined [NAME])}}, then281no types file is created during compilation and an existing types file282for this extension is assumed and installed.283284==== inline-file285286 [egg property] (inline-file [NAME])287288Specifies that an "inline" file should be generated and installed289for this component. This property is only used for extension290libraries. The name is optional and defaults to the291name of the extensions (with the proper extension).292293==== custom-build294295 [egg property] (custom-build STRING)296297Specifies a custom build script that should be executed instead of298the default build operations. This property is mandatory for299components of type {{generated-source-file}}. {{STRING}} should be the300name of a {{sh(1)}} shell command (e.g., a script) and thus may be platform301sensitive. The path to the file is prepended implicitly, so you302should '''not''' prefix it with {{./}}.303304The script will be invoked like the {{csc}} program and305is executed with the location of the CHICKEN306binaries in the {{PATH}}. Also, the following environment variables307are set in the execution environment of the script:308309* {{CHICKEN_CC}}: name of the C compiler used for building CHICKEN310* {{CHICKEN_CXX}}: name of the C++ compiler set during the build of CHICKEN311* {{CHICKEN_CSC}}: path to {{csc}}312* {{CHICKEN_CSI}}: path to {{csi}}313314315==== csc-options316317 [egg property] (csc-options OPTION ...)318319Specifies additional compiler options for {{csc}} that should be320used when building this component. If this property is not321given, the default options are used, which are {{-O2 -d1}}322for extensions and programs and {{-O2 -d0}} for import323libraries.324325Note that the options are quoted when passed to csc during the326compilation of the extension, so multiple options should be specified327as {{(csc-options "OPT1" "OPT2" ...)}} instead of {{(csc-options "OPT1 OPT2")}}328(the latter would be a single option containing a whitespace character).329330OPTION may optionally be a list of the form {{(custom-config FILENAME ARG ...)}},331which allows to dynamically determine options to be passed to the {{csc}}332program. FILENAME should be the name of a Scheme source file in the333current build directory. The file is invoked as {{csc -s FILENAME ARG ...}}334and should write s-expressions to stdout that are taken as additional335options to be passed to {{csc}} when compiling a component. The expressions336are read in, any list structure is flattened and all items are converted to337strings and added to the list of compilation options.338339==== link-options340341 [egg property] (link-options OPTION ...)342343Specifies additional link options for {{csc}} that should be344used when building this component.345346Note that the options are quoted when passed to csc during the347compilation of the extension, so multiple options should be specified348as {{(link-options "OPT1" "OPT2" ...)}} instead of {{(link-options "OPT1 OPT2")}}349(the latter would be a single option containing a whitespace character).350351Note that in order to pass linker options to the underlying C-compiler, these must352be prefixed with {{-L}}, eg. {{(link-options "-L" "-lpng")}}.353354This property supports {{custom-config}} specifications, described above.355356==== source357358 [egg property] (source NAME)359360Specifies an alternative source file, in case it has a name361distinct from the component name. By default the source file362for a component is named after the component, with the {{.scm}}363extension added.364365==== install-name366367 [egg property] (install-name NAME)368369Specifies an alternative installation name of the component,370if it differs from the actual component name. This property371is most useful if an egg installs an extension and a program372of the same name, but needs to distinguish the components during373build time.374375==== component-dependencies376377 [egg property] (component-dependencies NAME ...)378379Specifies dependencies to other components. {{NAME ...}} must380be the names of extension, program, scheme-include- or generated source file381components that should be built before the current component.382383==== source-dependencies384385 [egg property] (source-dependencies NAME ...)386387Specifies dependencies to additional source files. {{NAME ...}} must388denote filenames of which the program or extension depends.389A program or extension implicitly depends on its source file and390and on the egg-specification file.391392==== objects393394 [egg property] (objects NAME ...)395396Specifies that the components of type {{c-object}} should be linked397to this component and that the object components are dependencies.398399400==== destination401402 [egg property] (destination NAME)403404Specifies an alternative installation destination for the405built component and only applies406to components of type {{data}}, {{c-include}} and {{scheme-include}}.407This property should only be used in extreme408cases, as it is recommended to use the default installation409locations, which are:410411* for C include files: {{<PREFIX>/include/chicken/}}412413* for Scheme include files: {{<PREFIX>/share/chicken/}}414415* for data files: {{<PREFIX>/share/chicken/}}416417==== files418419 [egg property] (files NAME ...)420421Specifies source files for this component and only applies422to components of type {{data}}, {{c-include}} and {{scheme-include}}.423Both files and directories may be given and parent directories424are created as needed.425426==== modules427428 [egg property] (modules NAME ...)429430Specifies modules that the component (usually an extension) contains.431{{chicken-install}} will compile and install all import libraries for the given modules.432If this property is not given, then it is assumed that the extension has a single433module of the same name as the component.434435==== cond-expand436437 [egg property] (cond-expand CLAUSE ...)438439Similar to the toplevel {{cond-expand}} clause and may appear inside440component specifications.441442==== error443444 [egg property] (error STRING ARG ...)445446Similar to the toplevel {{error}} form, may appear inside component specifications.447448---449450Previous: [[Extension tools]]451452Next: [[Units and linking model]]